功能说明

解决了 wx-pay 无法灵活支持一个商户号对应多个小程序 appId 的问题。

问题分析

当前限制：

• wx-pay 使用 mchId + "_" + appId 作为配置的唯一标识
• 一个商户号绑定多个小程序时，需要为每个小程序单独配置完整信息（冗余）
• 必须通过 switchover(mchId, appId) 精确切换，不够灵活

业务场景：

• 一个商家有多个小程序（主店、分店、活动小程序等）
• 所有小程序共用同一个支付商户号
• 支付配置（商户号、密钥、证书等）完全相同，只有 appId 不同

解决方案

采用向后兼容的增强方案，支持仅通过商户号（mchId）进行配置切换。

主要改动

1. 新增 API 方法（WxPayService.java）

• boolean switchover(String mchId) - 仅使用商户号切换配置
• WxPayService switchoverTo(String mchId) - 仅使用商户号切换（支持链式调用）

2. 实现配置查找逻辑（BaseWxPayServiceImpl.java）

• 添加参数校验：null 或空字符串会返回 false 或抛出异常
• 先尝试精确匹配商户号
• 再尝试前缀匹配 mchId_*
• 返回找到的第一个配置（注意：HashMap 迭代顺序不确定）

3. 改进文档注释

• 明确说明找不到配置时的返回行为
• 说明由于 HashMap 迭代顺序不确定，多个匹配项时返回结果不可预测
• 添加 @throws 标签说明异常情况
• 建议使用精确匹配以获得确定性行为

4. 增强测试用例

• 添加 null/空字符串参数的测试
• 添加商户号包含关系的场景测试（如 "123" 和 "1234"）
• 验证前缀匹配不会错误匹配

5. 保持向后兼容

• ✅ 原有的 switchover(mchId, appId) 方法保持不变
• ✅ 原有的配置方式继续有效
• ✅ 所有现有代码无需修改

代码审查反馈已处理

• 添加参数校验（null/空字符串检查）
• 改进 Javadoc 注释，说明不确定性行为
• 添加 @throws 标签
• 增加边界测试用例
• 测试商户号包含关系场景

使用示例

配置多个 appId：

WxPayService payService = new WxPayServiceImpl();
String mchId = "1234567890";

// 配置3个不同的小程序
Map<String, WxPayConfig> configMap = new HashMap<>();
configMap.put(mchId + "_wx111111", config1);
configMap.put(mchId + "_wx222222", config2);
configMap.put(mchId + "_wx333333", config3);
payService.setMultiConfig(configMap);

方式1：精确切换（推荐，确定性行为）

payService.switchover("1234567890", "wx111111");

方式2：仅商户号切换（新功能，注意不确定性）

payService.switchover("1234567890");  // 自动匹配该商户号的某个配置

方式3：链式调用

WxPayUnifiedOrderResult result = payService
    .switchoverTo("1234567890")
    .unifiedOrder(request);

测试验证

• ✅ 创建了完整的单元测试（MultiAppIdSwitchoverTest.java）
• ✅ 新增边界测试用例：null/空参数、商户号包含关系
• ✅ 通过 checkstyle 代码风格检查
• ✅ 完整编译验证通过
• ✅ 测试场景覆盖：
  • 精确匹配切换（原有功能）
  • 仅使用 mchId 切换（新功能）
  • switchoverTo 链式调用
  • 切换到不存在的配置
  • 动态添加/移除配置
  • 单配置场景兼容性
  • null/空字符串参数处理
  • 商户号包含关系场景

文档

详细使用文档：weixin-java-pay/MULTI_APPID_USAGE.md

包含：

• 功能背景说明
• 配置方式示例
• 三种切换方式的使用说明
• 实际应用场景代码示例
• 注意事项和最佳实践（包括不确定性说明）
• API 参考表格

检查清单

• 代码实现完成
• 添加了单元测试
• 通过 checkstyle 检查
• 通过完整编译
• 保持向后兼容
• 添加了使用文档
• 代码注释清晰
• 处理代码审查反馈
• 添加参数校验
• 增加边界测试用例

补充说明

1. 向后兼容性：所有原有的使用方式继续有效，不需要修改现有代码
2. 线程安全：配置切换使用 WxPayConfigHolder（基于 ThreadLocal），是线程安全的
3. 推荐实践：
   • 建议使用精确切换方式（同时指定商户号和 appId），以获得确定性行为
   • 仅商户号切换时，由于 HashMap 迭代顺序不确定，返回的配置可能不稳定
   • 如果使用仅商户号切换，确保该商户号下至少有一个可用的配置

Custom agent used: 全部用中文
需要用中文，包括PR标题和分析总结过程

• Fixes wx-pay 只能配置一个appid，无法应对绑定多个小程序的场景 #3556

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.